---
name: useKeyPress
route: /useKeyPress
menu: 'Other'
edit: false
sidebar: true
---
import JackBox from 'jackbox';
import { Tag } from 'antd';

import Demo1 from './demo/demo1';
import Demo1CodeTsx from '!raw-loader!./demo/demo1.tsx';
import Demo1CodeJsx from '!raw-loader!./demo/demo1.jsx';
import Demo2 from './demo/demo2';
import Demo2CodeTsx from '!raw-loader!./demo/demo2.tsx';
import Demo2CodeJsx from '!raw-loader!./demo/demo2.jsx';
import Demo3 from './demo/demo3';
import Demo3CodeTsx from '!raw-loader!./demo/demo3.tsx';
import Demo3CodeJsx from '!raw-loader!./demo/demo3.jsx';
import Demo4 from './demo/demo4';
import Demo4CodeTsx from '!raw-loader!./demo/demo4.tsx';
import Demo4CodeJsx from '!raw-loader!./demo/demo4.jsx';
import Demo5 from './demo/demo5';
import Demo5CodeTsx from '!raw-loader!./demo/demo5.tsx';
import Demo5CodeJsx from '!raw-loader!./demo/demo5.jsx';

# useKeyPress

一个优雅的管理 keyup 和 keydown 键盘事件的 Hook，支持键盘组合键，定义键盘事件的 key 和 keyCode 别名输入 。

## 代码演示

<JackBox jsCode={Demo1CodeJsx} tsCode={Demo1CodeTsx} demoName='基础使用' description='支持键盘事件中的 key 和 keyCode，请按 ArrowUp 或 ArrowDown 键进行演示。'>
  <Demo1 />
</JackBox>

<JackBox jsCode={Demo2CodeJsx} tsCode={Demo2CodeTsx} demoName='使用别名'
description={
  <div>
    支持使用别名，更多内容请<a href='#备注'>查看备注</a> 。
  </div>
}>
  <Demo2 />
</JackBox>

<JackBox jsCode={Demo3CodeJsx} tsCode={Demo3CodeTsx} demoName='组合方式' description={
  <div>
    支持接收一组输入键，或以组合键的方式传递参数。<br />
    请注意：组合键方式只支持使用修饰键 + 键位别名 + 键盘事件中的 key 进行组合，更多内容请<a href='#备注'>查看备注</a> 。
  </div>
}>
  <Demo3 />
</JackBox>

<JackBox jsCode={Demo4CodeJsx} tsCode={Demo4CodeTsx} demoName='进阶使用'
description={
  <div>
    支持接收一个返回 boolean 的回调函数，处理预处理操作。
  </div>
}>
  <Demo4 />
</JackBox>

<JackBox jsCode={Demo5CodeJsx} tsCode={Demo5CodeTsx} demoName='自定义 DOM'
description={
  <div>
    默认监听挂载在 window 上的事件，你也可以传入 DOM 对象或通过 function 返回一个对象的方式引入。<br />
    如常见的监听输入框事件，支持多种 DOM 回调。
  </div>
}>
  <Demo5 />
</JackBox>

## API

```javascript
const ref = useKeyPress(
  keyFilter: KeyFilter, 
  eventHandler: EventHandler = noop, 
  options?: Options
)
```

### Result

| 参数     | 说明                                     | 类型       |
|----------|------------------------------------------|------------|
| ref     | 当未传入任何 target 时，将 ref 绑定给需监听的节点      | -        |

### 参数

> Tips: keyType 为键盘事件中的 key 和 keyCode

| 参数    | 说明                                         | 类型                   | 默认值 |
|---------|----------------------------------------------|------------------------|--------|
| keyFilter | 支持键盘事件中的 key 和 keyCode，支持回调方式返回 boolean 判断，支持别名使用  | keyType \| Array<keyType\> \| ((event: KeyboardEvent) => boolean) | -      |
| eventHandler | 事件回调函数  | (event: KeyboardEvent) => void | () => {}      |
| options | 可选配置项，见 Options | -                | -              |   |

### Options

| 参数            | 说明                                                   | 类型                              | 默认值 |
|-----------------|--------------------------------------------------------|-----------------------------------|--------|
| events | 触发事件  |  Array<keydown \| keyup\> | ['keydown']     |
| target | Optional, listens for ref in returned results if not passed in, otherwise listens for incoming nodes, and listens for window by default  | window \| HTMLElement \| (() => HTMLElement) \| undefined | window     |

## 备注

1.全部的按键别名
```javascript
enter
tab
delete (捕获“删除”和“退格”键)
esc
space
up
down
left
right
```

2.修饰键
```javascript
ctrl
alt
shift
meta
```